---
title: 处理脚本和事件
description: 如何使用浏览器 JavaScript API 将客户端交互界面添加到 Astro 组件
---
import ReadMore from '~/components/ReadMore.astro'

你可以通过在组件模版中使用 `<script>` 标签发送 JavaScript 到浏览器，并且为 Astro 组件添加各种功能。

脚本用来向你的网站添加交互性，比如处理事件或者动态更新内容，而无需任何像 React、Svelte 或者 Vue 这样的 [UI 框架](/zh-cn/guides/framework-components/)。这避免了随框架一起分发大量 JavaScript 的开销，也不需要你掌握任何额外框架就能创建功能齐全的网站或应用。

## 客户端脚本

脚本可以用来添加事件监听器，发送分析数据，播放动画，以及其他所有 JavaScript 可以在 Web 上做的事情。

Astro 会自动增强 HTML 标准的 `<script>` 标签，提供打包、TypeScript 等功能。有关更多详细信息，请参阅 [Astro 如何处理脚本](#脚本处理)。

```astro title="src/components/ConfettiButton.astro"
<button data-confetti-button>Celebrate!</button>

<script>
  // 从 npm 包导入
  import confetti from 'canvas-confetti';

  // 找到页面上的组件 DOM。
  const buttons = document.querySelectorAll('[data-confetti-button]');

  // 当 button 被点击时，添加事件监听器来触发 confetti。
  buttons.forEach((button) => {
    button.addEventListener('click', () => confetti());
  });
</script>
```

<ReadMore>了解 [何时你的脚本不会被处理](#未处理的脚本) 来排查脚本行为, 或了解如何有意选择退出此处理。</ReadMore>

## 脚本处理

默认情况下，Astro 会用以下方式处理不包含属性（除了 `src` 之外）的 `<script>` 标签：

- **TypeScript 支持：** 所有脚本默认使用 TypeScript。
- **导入打包：** 导入本地文件或 npm 模块，会被打包在一起。
- **模块类型：** 处理后的脚本会自动变成 [`type="module"`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules)。
- **去重：** 如果包含 `<script>` 的组件在页面上被多次使用，该脚本只会被包含一次。
- **自动内联：** 如果脚本足够小，Astro 会将其直接内联到 HTML 中，以减少请求次数。

```astro title="src/components/Example.astro"
<script>
  // 会处理！会打包！TypeScript！
  // 也可以导入本地脚本和 npm 包。
</script>
```

### 未处理的脚本

Astro 不会处理包含除了 `src` 以外任何属性的 `<script>`  标签。

你可以添加 [`is:inline`](/zh-cn/reference/directives-reference/#isinline) 指令来有意选择不对脚本进行处理。

```astro title="src/components/InlineScript.astro" "is:inline"
<script is:inline>
  // 将会被直接插入 HTML，不会有任何变化！
  // 不会被转换：没有 TypeScript，也没有被 Astro 解析导入。
  // 如果在组件内部使用，这段代码会为每个实例重复创建。
</script>
```

### 在你的页面中包含 JavaScript 文件

你可能希望将脚本编写为单独的 `.js`/`.ts` 文件，或者需要引用另一台服务器上的外部脚本。你可以通过在 `<script>` 标签的 `src` 属性中引用它们来做到这一点。

#### 导入本地脚本

**何时使用**：当你的脚本位于 `src/`。

Astro 将按照其[脚本处理规则](#脚本处理)处理这些脚本。

```astro title="src/components/LocalScripts.astro"
<!-- `src/scripts/local.js` 脚本的相对路径 -->
<script src="../scripts/local.js"></script>

<!-- 也适用于本地 TypeScript 文件 -->
<script src="./script-with-types.ts"></script>
```

#### 加载外部脚本

**何时使用：** 当你的 JavaScript 文件位于 `public/` 或 CDN 上。

要加载在项目的 `src/` 文件夹之外的脚本，请使用 `is:inline` 指令。当你如上所述导入脚本时，此方法会跳过 Astro 提供的 JavaScript 处理、打包和优化。

```astro title="src/components/ExternalScripts.astro" "is:inline"
<!-- `public/my-script.js` 脚本的绝对路径 -->
<script is:inline src="/my-script.js"></script>

<!-- 远程服务器上脚本的完整 URL -->
<script is:inline src="https://my-analytics.com/script.js"></script>
```

## 常见脚本模式

### 处理 `onclick` 和其他事件

一些 UI 框架使用自定义语法来处理事件，例如 `onClick={...}` (React/Preact) 或 `@click="..."` (Vue)。Astro 更严格地遵循标准 HTML，并且不对事件使用自定义语法。

相反，你可以在 `<script>` 标签中使用 [`addEventListener`](https://developer.mozilla.org/zh-CN/docs/Web/API/EventTarget/addEventListener) 来处理用户交互。

```astro title="src/components/AlertButton.astro"
<button class="alert">Click me!</button>

<script>
  // 在页面上找到所有带有 `alert` 类的按钮。
  const buttons = document.querySelectorAll('button.alert');

  // 处理每个按钮上的点击事件。
  buttons.forEach((button) => {
    button.addEventListener('click', () => {
      alert('按钮被点击了！');
    });
  });
</script>
```

如果你在一个页面上有多个 `<AlertButton />` 组件，Astro 将不会多次运行该脚本。脚本是打包在一起的，每页只包含一次。使用 `querySelectorAll` 确保此脚本将事件侦听器附加到页面上找到的具有 `alert` 类的每个按钮。

### 具有自定义元素的 Web 组件

你可以使用 Web 组件标准创建具有自定义行为的 HTML 元素。在 `.astro` 组件中定义 [自定义元素](https://developer.mozilla.org/zh-CN/docs/Web/Web_Components/Using_custom_elements) 允许你构建交互式组件而无需 UI 框架库。

在这个例子中，我们定义了一个新的 `<astro-heart>` HTML 元素，用于跟踪你点击喜欢按钮的次数并使用最新计数更新 `<span>`。

```astro title="src/components/AstroHeart.astro"
<!-- 将按钮包装在我们的自定义元素“astro-heart”中。 -->
<astro-heart>
  <button aria-label="Heart">💜</button> × <span>0</span>
</astro-heart>

<script>
  // 为我们的新 HTML 自定义元素定义行为。
  class AstroHeart extends HTMLElement {
    connectedCallback() {
      let count = 0;

      const heartButton = this.querySelector('button');
      const countSpan = this.querySelector('span');

      // 每次单击按钮时，更新计数。
			heartButton.addEventListener('click', () => {
        count++;
        countSpan.textContent = count.toString();
      });
		}
  }

  // 告诉浏览器将我们的 AstroHeart 类用于 <astro-heart> 元素。
  customElements.define('astro-heart', AstroHeart);
</script>
```

在这里使用自定义元素有两个优点：

1. 除了使用 `document.querySelector()` 搜索整个页面，你可以使用 `this.querySelector()` ，它只在当前自定义元素实例中搜索。这使得一次只处理一个组件实例的子实例变得更容易。

2. 虽然 `<script>` 只运行一次，但浏览器每次在页面上找到 `<astro-heart>` 时都会运行我们自定义元素的 `connectedCallback()` 方法。这意味着你可以安全地一次为一个组件编写代码，即使你打算在一个页面上多次使用该组件。

<ReadMore>你可以在[web.dev 的《可重用 Web 组件指南》](https://web.dev/custom-elements-v1/)和[MDN 对自定义元素的介绍](https://developer.mozilla.org/zh-CN/docs/Web/Web_Components/Using_custom_elements)中了解更多自定义元素。</ReadMore>

### 将 frontmatter 变量传递给脚本

在 Astro 组件中，[frontmatter](/zh-cn/basics/astro-components/#组件脚本)（`---` 之间）中的代码在服务器上运行，而不是在浏览器中。

要将服务端变量传递给客户端脚本，可以使用 [`data-*` 属性](https://developer.mozilla.org/zh-CN/docs/Learn/HTML/Howto/Use_data_attributes) 在 HTML 中存储它们。脚本就可以使用 `dataset` 属性读取这些属性。

在此示例组件中，一个 `message` 属性存储在 `data-message` 属性中，因此自定义元素可以读取 `this.dataset.message` 并在浏览器中获取该属性的值。

```astro title="src/components/AstroGreet.astro" {2} /data-message={.+}/ "this.dataset.message"
---
const { message = '你好，世界！' } = Astro.props;
---

<!-- 将消息存储为数据属性。 -->
<astro-greet data-message={message}>
  <button>Say hi!</button>
</astro-greet>

<script>
  class AstroGreet extends HTMLElement {
    connectedCallback() {
      // 从 data（数据）属性中读取消息。
      const message = this.dataset.message;
      const button = this.querySelector('button');
      button.addEventListener('click', () => {
        alert(message);
      });
		}
  }

  customElements.define('astro-greet', AstroGreet);
</script>
```
现在我们可以多次使用我们的组件，并且每次都会收到不同的消息。

```astro title="src/pages/example.astro"
---
import AstroGreet from '../components/AstroGreet.astro';
---

<!-- 使用默认消息：“你好，世界！” -->
<AstroGreet />

<!-- 使用作为 props 传递的自定义消息。 -->
<AstroGreet message="构建组件的美好一天！" />
<AstroGreet message="很高兴你做到了！👋" />
```

:::tip[你知道吗？]
当你将 props 传递给使用 React 等 UI 框架编写的组件时，这实际上是 Astro 在幕后所做的！对于带有 `client:*` 指令的组件，Astro 创建了一个带有 `props` 属性的 `<astro-island>` 自定义元素，该属性将你的服务器端 props 存储在 HTML 输出中。
:::

### 脚本和 UI 框架相结合

当 `<script>` 标签执行时，由 UI 框架渲染的元素可能还不可用。如果你的脚本还需要处理 [UI 框架组件](/zh-cn/guides/framework-components/)，建议使用自定义元素。
